import TroubleshootingLLMConnectivity from './common/troubleshooting-llm-connectivity.mdx';

# 选择 AI 模型

选择以下模型之一，获取 API 密钥，完成配置，即可开始使用 Midscene.js。如果你是初学者，请选择最容易获得的模型。

## Midscene.js 已适配的模型

Midscene.js 支持两种类型的模型：视觉语言模型和 LLM 模型。

### 视觉语言模型（VL 模型，✨ 推荐）

Midscene 调用了一些视觉语言模型（VL 模型），无需依赖 DOM 信息就能精确定位页面上目标元素的坐标。

在我们的实践中，这些模型已经能覆盖大部分需求场景，相比 LLM 模型成本也显著更低，因此我们推荐在 UI 自动化中优先使用 VL 模型。此外，借助这些模型，Midscene 不仅可以驱动 Web 自动化，也可以操作 Android、iOS 以及其他任何界面，这种方式更加直观、高效。

以下是已适配的 VL 模型：

* [千问 VL](#qwen3-vl-or-qwen-25-vl)
* [豆包系列视觉语言模型](#doubao-vision)
* [`Gemini-2.5-Pro`](#gemini-25-pro)
* [`UI-TARS`](#ui-tars)

### LLM 模型（将在下一个大版本移除）

能够理解文本和图像输入的多模态 LLM 模型。GPT-4o 就是这种类型的模型。

多模态 LLM 目前仅可用于 Web 自动化，其中较典型的模型是 [GPT-4o](#gpt-4o)。如有需要，你也可以使用[其他 LLM 模型](#其他-llm-模型)。

## 深入了解模型

<div id="doubao-vision"></div>

### 豆包系列视觉语言模型（✨ 推荐）

火山引擎提供了多个视觉语言模型，包括：

* `Doubao-seed-1.6-vision`（更新且更优秀）
* `Doubao-1.5-thinking-vision-pro`

它们在复杂场景的视觉定位和断言方面表现相当出色。在指令清晰的情况下，能满足绝大多数业务场景需求。

**配置**

从 [火山引擎](https://volcengine.com) 获取 API 密钥后，可以使用以下配置：

```bash
OPENAI_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" 
OPENAI_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_USE_DOUBAO_VISION=1
```

**链接**
- [火山引擎 - Doubao-1.5-thinking-vision-pro](https://www.volcengine.com/docs/82379/1536428)
- [火山引擎 - Doubao-Seed-1.6-Vision](https://www.volcengine.com/docs/82379/1799865)

<div id="qwen3-vl-or-qwen-25-vl"></div>

### 千问 VL（✨ 推荐）

Qwen-VL（千问 VL）是阿里巴巴发布的开源模型系列。它提供视觉定位能力，可以准确返回页面上目标元素的坐标。在用于交互、断言和查询时的综合表现相当出色。你可以在 [阿里云](https://help.aliyun.com/zh/model-studio/vision) 或 [OpenRouter](https://openrouter.ai/qwen) 上找到 Qwen 系列的已部署版本。

Midscene.js 支持使用以下版本的模型：
* Qwen3-VL 系列，包括 `qwen3-vl-plus` (商业版) 和 `qwen3-vl-235b-a22b-instruct` (开源版)
* Qwen2.5-VL 系列

我们推荐使用 Qwen3-VL 系列，因为它的表现明显优于 Qwen2.5-VL。使用 Qwen3-VL 系列的模型要求搭配 Midscene v0.29.3 及以上的版本。

**使用 Qwen3-VL 模型的配置**

以阿里云 `qwen3-vl-plus` 模型为例：

```bash
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen3-vl-plus"
MIDSCENE_USE_QWEN3_VL=1 # 注意，这个参数与 MIDSCENE_USE_QWEN_VL 不能同时使用
```

**使用 Qwen2.5-VL 模型的配置**

以阿里云 `qwen-vl-max-latest` 模型为例：

```bash
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="qwen-vl-max-latest"
MIDSCENE_USE_QWEN_VL=1 # 注意，这个参数与 MIDSCENE_USE_QWEN3_VL 不能同时使用
```

**链接**
- [阿里云 - Qwen-VL 系列](https://help.aliyun.com/zh/model-studio/vision)
- [Qwen on 🤗 HuggingFace](https://huggingface.co/Qwen)
- [Qwen on Github](https://github.com/QwenLM/)
- [Qwen on openrouter.ai](https://openrouter.ai/qwen)

<div id="gemini-25-pro"></div>

### `Gemini-2.5-Pro`

从 0.15.1 版本开始，Midscene.js 支持 Gemini-2.5-Pro 模型。Gemini 2.5 Pro 是 Google Cloud 提供的闭源模型。

使用 Gemini-2.5-Pro 时，你应该使用 `MIDSCENE_USE_GEMINI=1` 配置来开启 Gemini-2.5-Pro 模式。

**配置**

在 [Google Gemini](https://gemini.google.com/) 上申请 API 密钥后，可以使用以下配置：

```bash
OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="......"
MIDSCENE_MODEL_NAME="gemini-2.5-pro-preview-05-06"
MIDSCENE_USE_GEMINI=1
```

**链接**
- [Gemini 2.5 on Google Cloud](https://cloud.google.com/gemini-api/docs/gemini-25-overview)

<div id="ui-tars"></div>

### `UI-TARS`

UI-TARS 是基于 VLM 架构的端到端 GUI 代理模型。它仅感知截图作为输入，并执行类似人类的交互（例如键盘和鼠标操作），在 10 多个 GUI 基准测试中实现了最先进的性能。UI-TARS 是一个开源模型，并提供不同大小的版本。

使用 UI-TARS 时，你可以使用目标驱动风格的提示，如"使用用户名 foo 和密码 bar 登录"，它会规划步骤来实现目标。

**配置**

你可以在 [火山引擎](https://volcengine.com) 上使用已部署的 `doubao-1.5-ui-tars`。

```bash
OPENAI_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" 
OPENAI_API_KEY="...."
MIDSCENE_MODEL_NAME="ep-2025..." # 来自火山引擎的推理接入点 ID 或模型名称
MIDSCENE_USE_VLM_UI_TARS=DOUBAO
```

**限制**

- **断言表现不佳**：它在断言和查询方面可能不如 GPT-4o 和 Qwen 2.5。
- **操作路径不稳定**：它可能会尝试不同的路径来实现目标，因此每次调用的操作路径不稳定。

**关于 `MIDSCENE_USE_VLM_UI_TARS` 配置**

`MIDSCENE_USE_VLM_UI_TARS` 配置用于指定 UI-TARS 版本，使用以下值之一：
- `1.0` - 用于模型版本 `1.0`
- `1.5` - 用于模型版本 `1.5`
- `DOUBAO` - 用于在火山引擎上部署的模型

**链接**
- [UI-TARS on 🤗 HuggingFace](https://huggingface.co/bytedance-research/UI-TARS-72B-SFT)
- [UI-TARS on Github](https://github.com/bytedance/ui-tars)
- [UI-TARS - Model Deployment Guide](https://juniper-switch-f10.notion.site/UI-TARS-Model-Deployment-Guide-17b5350241e280058e98cea60317de71)
- [UI-TARS on Volcengine](https://www.volcengine.com/docs/82379/1536429)


<div id="gpt-4o"></div>
### `GPT-4o`

GPT-4o 是 OpenAI 的多模态 LLM，支持图像输入。这是 Midscene.js 的默认模型。使用 GPT-4o 时，建议使用逐步提示。

由于 Midscene 需要向模型发送一些 DOM 信息和截图，使用 GPT-4o 的 token 成本较高，并且在复杂场景中不够稳定。

**配置**

```bash
OPENAI_API_KEY="......"
OPENAI_BASE_URL="https://custom-endpoint.com/compatible-mode/v1" # 可选，如果你想要使用不同于 OpenAI 默认的接入点
MIDSCENE_MODEL_NAME="gpt-4o-2024-11-20" # 可选，默认是 "gpt-4o"
```

<div id="其他-llm-模型"></div>
## 选择其他多模态 LLM

Midscene.js 也支持其他模型。对于这些模型，Midscene 将使用与 GPT-4o 相同的提示和策略。如果你想使用其他模型，请按照以下步骤操作：

1. 需要多模态模型，这意味着它必须支持图像输入。
1. 模型越大，效果越好。但是，它需要更多的 GPU 或资金。
1. 找出如何使用与 OpenAI SDK 兼容的接入点调用它。通常你应该设置 `OPENAI_BASE_URL`、`OPENAI_API_KEY` 和 `MIDSCENE_MODEL_NAME`。配置说明请参见[配置模型和服务商](./model-provider)。
1. 如果在更换模型后发现效果不佳，可以尝试使用一些简短清晰的提示，或者回滚到之前的模型。更多详情请参见[提示技巧](./prompting-tips)。
1. 请记住遵守每个模型和服务商的使用条款。
1. 除非你知道自己在做什么，否则不要包含 `MIDSCENE_USE_VLM_UI_TARS` 和 `MIDSCENE_USE_QWEN_VL` 配置。

**配置**

```bash
MIDSCENE_MODEL_NAME="....."
OPENAI_BASE_URL="......"
OPENAI_API_KEY="......"
```

更多详细信息和示例配置，请参见[配置模型和服务商](./model-provider)。

## 常见问题

### 如何查看模型的 token 使用情况？

通过在环境变量中设置 `DEBUG=midscene:ai:profile:stats`，你可以打印模型的使用信息和响应时间。

你也可以在报告文件中查看模型的使用信息。

### 收到了 "No visual language model (VL model) detected" 错误

请确保你正确配置了 VL 模型，特别是 `MIDSCENE_USE_...` 配置是否正确。

## 更多信息

* 想了解更多模型配置，请参见[配置模型和服务商](./model-provider)
* [编写提示词（指令）的技巧](./prompting-tips)

<TroubleshootingLLMConnectivity />
